home *** CD-ROM | disk | FTP | other *** search
/ 130 MIDI Tool Box / 130 MIDI Tool Box.iso / sysex / sysex.doc next >
Text File  |  1991-05-01  |  12KB  |  346 lines
  1. =================================================================
  2.                    SYSEX -Yet Another Sysex Program
  3. =================================================================
  4.  
  5. This  is yet  another program  that sends/receives  SYSEX data. I
  6. wrote it because I feel it  offers some capabilities not found in
  7. other similar programs. It has  proved very usefull while working
  8. with my YAMAHA TG55, for which I dont have a patch editor yet.
  9.  
  10. This software is public domain. Use  it or change it as you wish.
  11. I am uploading the source (Turbo pascal 5) for anybody interested
  12. to modify it. If you have  any problems, I would be interested to
  13. hear about them, and, possibly, to suggest a solution. In fact,if
  14. anybody  finds it  usefull, PLEASE   drop me  a note.  This would
  15. encourage  me to  upload other   programs I  will develop  in the
  16. future. Future versions of this program will appear if, and when,
  17. I will  receive  any  problem   reports  and/or  suggestions  for
  18. extensions.
  19.  
  20. (Note that I am uploading from  Greece, which means that it costs
  21. me about  1$ per minute...  So, I would  like to know  whether my
  22. uploads are helpfull  to anybody, or are just  falling in a black
  23. hole.)
  24.  
  25. Overview
  26. --------
  27.  
  28. SYSEX is  a program that can  send and receive SYSEX  data to any
  29. synthesizer. Its main features include the capability to create
  30. interactive  dump  request  files,  the  automatic calculation of
  31. checksums, and the ability to work with human-readable files.
  32.  
  33. System requirements are :
  34.  
  35.  1. IBM clone with at least 256K.
  36.  2.  MPU-401  compatible  interface,  standard configuration
  37.      (IRQ 2, Base 330h).
  38.  
  39.  
  40. Program operation
  41. -----------------
  42.  
  43. The command format is : SYSEX <Filename1> [<filename2>] /options
  44.  
  45. Depending  on the  required  mode,  filename2 and/or  options are
  46. optional. If  the names have  no extension, an  extension of .SYX
  47. will be assumed.
  48.  
  49. If SYSEX  is typed with  no parameters, a  breif help message  is
  50. displayed.
  51.  
  52. There are 4 main modes of operation :
  53.  
  54. 1. Send a file to the synth
  55. ---------------------------
  56.  
  57.    Format  : SYSEX <filename1>
  58.    Options : None
  59.  
  60. The main use of this mode is  to send bulk data (like voice info)
  61. to the synth.
  62.  
  63. The  file is  assumed (and  checked) to  be a  series of properly
  64. formatted  sysex  messages,  i.e  any  number  of blocks with the
  65. format : <SYSEXSTART> data bytes <SYSEXEND>.
  66.  where sysexstart is F0h, and sysexend is F7h.
  67. The  blocks  must  be  consecutive,  without  any  intervening or
  68. missing bytes, for example :
  69.  
  70. F0 dd dd dd F7 F0 dd dd dd dd dd F7
  71.  
  72. Missing or superflous start/end bytes will be reported as errors.
  73.  
  74. If  there are  more than  one blocks,  the program  will insert a
  75. delay of at least 110  milliseconds between transmissions of each
  76. block. This  is required by  some synths. If  this number is  not
  77. enough, recompile  the program changing the  values in the <WAIT>
  78. routine..
  79.  
  80.  
  81. 2. Send a dump request , and receive a sysex dump
  82. -------------------------------------------------
  83.  
  84.    Format : SYSEX <filename1> <filename2>
  85.  
  86. For <filename1>, all comments for mode 1 apply. The program will:
  87.  
  88. a. transmit the first file, as in mode 1
  89. b. wait for sysex data to come in.
  90. c. Store the received bytes in <filename2>
  91.  
  92. Since  there is  no reliable  way to  know when  a sysex dump has
  93. finished, (as it may consist of more than one blocks),the program
  94. will  continue  receiving  and  storing  bytes  until  any key is
  95. pressed. To help you know when a sysex dump has finished, it will
  96. display a  receive bytes count. While  this number is increasing,
  97. the synth is  sending data. When this number  is stable, you know
  98. that the synth has finished transmission, and you can hit any key
  99. to end the receive and store the data.
  100.  
  101. 3. Receive a bulk dump started manually from the synth pannel
  102. -------------------------------------------------------------
  103.  
  104.    Format :SYSEX <Filename1> /m
  105.  
  106.  The  program works  like mode  2, but  skips the  first step  of
  107.  sending a file. It waits for the  data to come in, and the saves
  108.  them in filename1.
  109.  
  110. 4. Convert between file formats
  111. -------------------------------
  112.  
  113.    Format SYSEX <filename1> <filename2> /c
  114.  
  115. In this mode, the program reads-in  the first file, and stores it
  116. in the second file. No interaction is done with the synth at all.
  117.  
  118. This mode  is usefull for converting  between file formats, since
  119. the input  and output formats  can be different.  See notes about
  120. file formats.
  121.  
  122. File formats
  123. ------------
  124.  
  125. The program recognises and generates two file formats, depending
  126. on the file name suffix:
  127.  
  128. if a  suffix of .TXT  is given, the  program assumes TXT  (Ascii)
  129. format.
  130.  
  131. if any other suffix is  given, the program assumes sysex (binary)
  132. format.
  133.  
  134. If no suffix  is given, the program assumes  .SYX, and interprets
  135. the file as binary (same as above).
  136.  
  137. Format Description
  138. ------------------
  139.  
  140. a. SYSEX files.
  141. --------------
  142. These are  standard SYSEX (or  MIDIEX, as some  call them) files,
  143. which are an exact binary  image of the sent/received data. There
  144. are no headers or any other extra bytes. These "pure" sysex files
  145. can  be handled  by most  sequencers. While  usefull, they do not
  146. offer  any extra  capabilities. When  using this  kind of  files,
  147. SYSEX works like any other sysex-exchange program.
  148.  
  149. b. TXT files
  150. ------------
  151.  
  152. This format is peculiar to  the SYSEX program. Conceptually it is
  153. the same with format (a), but with two  major differences :
  154.  
  155.  1. The  data are stored in  ASCII format, which means  that they
  156.     can be created/edited with any ascii word prossesor/editor.
  157.     Therefore, if you loaded the  file with a standard editor,you
  158.     would see something like :
  159.  
  160.      F0 10 11 13 F7
  161.  
  162.     (In contrast,  if you loaded  a format(a) file  in an editor,
  163.     you would see "garbage", like smiling faces etc)
  164.  
  165.     Values are  delimited by any  number of spaces,  and the line
  166.     length  is limited  to 254  chars. There  should be  no blank
  167.     lines, since  this will terminate  file input. (This  feature
  168.     can be  used to add a  large block of comments  at the end of
  169.     the file, by  separating the comments from the  data with one
  170.     or more blank lines. Make  sure that any blank lines inserted
  171.     for this  purpose are REALLY  blank, i.e zero  length, and do
  172.     not  include any  spaces. Remember  that a  zero length  line
  173.     LOOKS the same as one that consists of spaces only).
  174.  
  175.     The  error checking  is  rather  rudimentary, so  be carefull
  176.     about the data format...
  177.  
  178.  2. When a file in this  format is TRANSMITTED, there is a number
  179.     of special constructions that SYSEX will recognise. These can
  180.     be embedded in the text,  and make all the difference between
  181.     using  this TXT  format and  the standard  sysex format  (a).
  182.     These are :
  183.  
  184.      1. 'any text'.
  185.  
  186.         If  any text  is  put  between quotes,  the corresponding
  187.         ascii values will be sent.  This helps you put ascii data
  188.         like voice names in the  text, without reverting to ascii
  189.         tables and such.
  190.  
  191.         e.g. : F0 43 20 'AB' 20 21 22 F7 actually is sent as :
  192.                          ││
  193.                          │└┐
  194.                F0 43 20 41 42 20 21 22 F7
  195.  
  196.      2. ;any text.
  197.  
  198.          A  semicolon makes  SYSEX ignore  the rest  of the line.
  199.          Usefull for comments.
  200.  
  201.      3. | xx xx.
  202.  
  203.         The  bar (|)  will send  the logical  OR of  the next two
  204.         values. This is especially usefull with the ? construct
  205.         (see below).
  206.  
  207.          E.g  F0 | 01 02 F7 =  F0 03 F7  (03= OR of 01 and 02)
  208.  
  209.  
  210.      4. ?Prompt
  211.  
  212.          You will be prompted for  a value, and this will replace
  213.          this  construct.  Usefull  for  making  parametric  dump
  214.          request files.  For example, let's  say that your  synth
  215.          sends  a particular  part data  with the  following dump
  216.          request :
  217.  
  218.           F0 43 01 2n F7 , where n is the part required.
  219.  
  220.          Combining  constructs ?  and |  , you  would create the
  221.          following dump request file :
  222.  
  223.           F0 43 01 | 20 ?Part F7
  224.  
  225.          This line would result in the program asking :
  226.  
  227.           Part :
  228.  
  229.          After  you type  in the  part value (n),  this will be ORed
  230.          with 20h to give the required 2n.
  231.  
  232.          Hint : If you want to type in the value in hex , precede
  233.          it by a $ sign. For example : $3F
  234.  
  235.      5.  @,#  pair.  These  constructs  are  used  to  make SYSEX
  236.          calculate  7-bit  checksum  values  for  you (which some
  237.          synths require). When @ appears, the checksum counter is
  238.          zeroed. From this point onward, each byte transmitted is
  239.          calculated in the checksum, until  a # appears, which is
  240.          then replaced  by the 2's complement  of the checksum. I
  241.          have tested  this with ROLAND  and YAMAHA synths  and it
  242.          works fine, saving all the work of calculating checksums
  243.          by hand...  Remember, not ALL  bytes in a  sysex message
  244.          take  part in  the checksum,   thus the  need for  the @
  245.          character  to   signify  the  starting   point  for  the
  246.          calculation. This capability was the main reason I wrote
  247.          this program...
  248.  
  249.          Example : F0 43 20 @ 01 02 03 # F7
  250.                             └─ start   └── checksum
  251.                                       ┌───────┘
  252.          results : F0 43 20 01 02 03 7A F7
  253.  
  254.  
  255. Tips about using TXT files
  256. --------------------------
  257.  
  258. 1.  Since each  file name  in  a  command can  be in  a different
  259.     format, you can use SYSEX  to do format conversions. Also, if
  260.     you  want to  check your  parametric dump  files, you can use
  261.     SYSEX to see what exactly will be transmitted. For example,if
  262.     you have created a file  DUMP.TXT that has special constructs
  263.     in it, you can use the command :
  264.  
  265.     SYSEX DUMP.TXT DEBUG.TXT /c
  266.  
  267.     If you then  edit the resulting DEBUG.TXT file,  it will show
  268.     the  exact sequence  sent to  the synth,  with all constructs
  269.     replaced.
  270.  
  271. 2.  It is  best to  keep your  dump request  files in TXT format,
  272.     since  it is  easier to  edit/maintain them.  Synth-generated
  273.     bulk dump files,  on the other hand, should  be kept in sysex
  274.     format, since there are probably no usefull substitutions you
  275.     would  want to  make during  uploading such  a file,  and the
  276.     sysex format works MUCH faster. In any case, you can convert
  277.     between formats with the /C option at any time..
  278.  
  279.  
  280. Examples of usage:
  281. -----------------
  282.  
  283. 1. send file sounds1.syx to the synth
  284.  
  285.  SYSEX SOUNDS1  or SYSEX SOUNDS1.SYX  (.SYX is default)
  286.  
  287. 2. receive a bulk dump. Bulk request is in TXT format, save dump in
  288.    sysex format :
  289.  
  290.    SYSEX REQUEST.TXT SAVED or
  291.    SYSEX REQUEST.TXT SAVED.VOI (any  suffix but TXT, means binary
  292.                                file)
  293.  
  294. 3. receive a manual-started  bulk dump, save in TXT :
  295.  
  296.     SYSEX SAVED.TXT /m
  297.  
  298. 4. convert between TXT and sysex formats :
  299.  
  300.     SYSEX REQUEST.TXT REQUEST.BIN /c or
  301.     SYSEX REQUEST.BIN REQUEST.TXT /c
  302.  
  303.  
  304.  
  305. Limitations
  306. -----------
  307.  
  308. The  maximum  buffer  size  is  currently  50,000 bytes, so files
  309. larger than this cannot be sent/received.
  310.  
  311. Error messages
  312. --------------
  313.  
  314. Input file not found
  315.   the program cannot find the file
  316.  
  317. File too large
  318.  buffer limit exceeded for input file
  319.  
  320. Too many data in
  321.  received data exceed buffer limit
  322.  
  323. Format error, missing Start of Exclusive
  324.  Blocks are not correctly formatted, see notes about transmitting
  325.  files to the synth
  326.  
  327. Cannot create dest
  328.  Error while opening  output file. Error in name,  or no space on
  329.  disk
  330.  
  331. Acknowledgments
  332. ---------------
  333.  
  334. I have used a unit downloaded from CIS, originally named MPU401,
  335. with heavy modifications. It is quoted as created by John Sloan.
  336. My thanks to him.
  337.  
  338. The idea of macro constructs, and the .SYX suffix come from
  339. Greg Hendershott's fine CAKEWALK program. Special thanks.
  340.  
  341.  
  342.  
  343. Mike Cariotoglou,Greece
  344.  
  345. CIS 10012,1767
  346. BIX avoreadis